# Game installation instructions

Minimal requirements:

 * Any installation of `wine` >= 5.3 (sooner or later)
 * MS core fonts
     * Ubuntu/Debian: install `ttf-mscorefonts-installer`
     * Arch/Manjaro: install `ttf-ms-fonts`
     * Alternatively: winetricks `corefonts` verb (after wineprefix setup)

Highly recommended:

 * Vulkan-capable graphics card (["How to check?"](TROUBLESHOOTING.md#graphics-bugsissues))


### Table of contents

* [Lutris](#lutris)
* [Steam](#steam)
* [SteamOS](#steamos)
* [Custom](#custom)
* [macOS instructions](#macos-instructions)
* [Bilibili](#bilibili)
* [Controller Configuration](#controller-configuration)


#### Lutris

1. Download the Windows installer from the official site
2. Add the installer binary to your library
3. Set up a wineprefix for the game
    * This is where the game will be installed. 40+ GiB of free space is highly recommended.
    * Grab a recent Wine runner. See [TROUBLESHOOTING](TROUBLESHOOTING.md) for problematic versions
4. Install the components the game needs to run flawlessly
    * Enable DXVK in `Configuration` -> `Runner options` (1.7.3 or newer is recommended)
    * Navigate to `Configuration -> Runner options` -> `DLL overrides` (table) and add the
      entry `avcodec-58.dll` with value `d`. This avoids crashes (see Issue #339)
5. Launch the downloaded installer .exe
    * Use the `Run EXE inside wine prefix` menu action for this.
    * The C++ Redistributable Package is optional. You may cancel it.
    * Download and install the game files.
    * **Once it is done, do not press launch.** Exit the launcher.
6. Apply the patch script: ["how?"](README.md)
7. Change the executable path. `Configuration` -> `Game options`
    * Executable: `launcher.bat`
    * Working directory: select the directory where `GenshinImpact.exe` resides
8. Launch the game


**Important note:**

After setup you might have multiple Wine versions and multiple WINEPREFIX directories
on your system. Hence running the `wine` command from your terminal will use another
environment than Lutris does.

To open a command prompt which uses the correct environment, do either:

 * Games -> Wine options (see bottom status bar or left side) -> `Wine console`
 * Change the `Executable` path to `cmd.exe`


#### Steam

1. Download the official launcher
2. "Add non-Steam game..." -> Browse -> Show all files -> Select the installer executable -> Done
3. Setup proton (if not done using global settings)
    * Navigate: Gear icon -> "Settings" -> "Compatibility"
    * Check "Force compatibility layer ..."
    * Select a recent Proton version
4. Install the launcher and start it
    * The C++ Redistributable Package is optional. You may cancel it.
    * Download and install the game files.
5. Apply the patch script: ["how?"](README.md)
6. Update the target. Gear icon -> "Settings":
    * Target: `explorer.exe`
    * Execution directory: the directory where `GenshinImpact.exe` resides
    * Start options: `%command% /desktop=anyname,1920x1080 cmd /c launcher.bat`
    * Adjust the screen resolution above, if necessary.
7. Play.
    * For CN version + Steam Deck: you might need to [add environment variables](TROUBLESHOOTING.md#game-crashes-on-launch) to start the game.


#### SteamOS

This section is based on the Steam instructions above.

1. The patches may modify `/etc/hosts` which is not writable by default.
     * Option 1: Use `sudo steamos-readonly disable` before running the main patch
       script and make the file system readonly again after completion: `sudo steamos-readonly enable`
         * Note: The changes done by the script might be undone by system updates.
     * Option 2: Allow the analytics domains in the patch script. Refer to [static/analytics_summary.txt](static/analytics_summary.txt)
       for an overview of the collected data.
     * Option 3: Use a semi-isolated container to avoid this problem such as Flatpak.
       For example, the third party launcher "An Anime Game Launcher"
       (see [updater/README.md](updater/README.md) for links) offers such package.
2. For Chinese/Japanese players: (to fix [startup crashes](TROUBLESHOOTING.md#game-crashes-on-launch))
     1. Run the script `compat/steamos_CJ_locale_enabler.sh` to generate the necessary locale
     2. Configure `LC_ALL` as described in [TROUBLESHOOTING.md](TROUBLESHOOTING.md#game-crashes-on-launch)


#### Custom

Script-based approach to use any Wine version on any WINEPREFIX.
If you do not understand what each step is supposed to do, use Lutris instead.

For the final game launch script after the prefix setup, use steps 1, 2 and 6.

	# 1. Specify the path to wine(64)
	#    This can be either system-wide or a custom installation
	WINE="wine64"
	#WINE="/path/to/custom/wine/build/bin/wine64"

	# 2. Specify a WINEPREFIX
	export WINEPREFIX="/absolute/path/to/.prefix/"

	# 3. Create or update WINEPREFIX
	"$WINE" wineboot -u

	# 4. Install DXVK (v1.9.4, for Wine 5.14+)
	#    Use the newest Winetricks script from GitHub
	export WINE
	sh winetricks dxvk194

	# 5. Install the game (if not already done)
	"$WINE" "/path/to/installer.exe"

	# 6. Game launch
	#    Using a virtual desktop with a size of 1920x1080 pixels
	cd "/path/to/Genshin Impact Game"
	export WINEESYNC=1  # requires staging or Proton, see TWEAKS.md
	"$WINE" explorer /desktop=anyname,1920x1080 cmd /c launcher.bat

	# 7. Game update
	#    See `updater/README.md` or attempt to use the official launcher:
	"$WINE" "/path/to/official/launcher.exe"


#### macOS instructions

It's highly recommended to use CrossOver using a recent [DXVK-macOS](https://github.com/Gcenx/DXVK-macOS) version.

 * Note: Confirmed working with DXVK-macOS 1.10.3-47.

MoltenVK does yet not support `VK_EXT_transform_feedback` (see issue #374), which can be
worked around by the following patch. Check the script contents for details.

    bash "/path/to/dawn/compat/macos_cpu_skinning.sh"


To fix further rendering issues on low-end Macs, open or create the file `dxvk.conf` in the game
directory and add the following line: (requires a working DXVK installation)

    dxgi.customDeviceDesc = "AMD Radeon Pro 5300M"

 * Note: CrossOver might come with an old DXVK version which does not handle this option.
 * Note: Setting the device ID and vendor ID does not have any effect.

Confirm whether the changes are in effect:

1. Start the game
2. Open the `*_dxgi.log` file in the game directory
2. The line starting containing `DXVK:` must mention a recent version (e.g. 1.10.3)
3. The line below `Effective configuration:` must mention the GPU specified in `dxvk.conf`.
4. Visual test: compare the in-game graphics


#### Bilibili

**Chinese**

(feel free to translate / 随意翻译)



**English**

Wine Gecko 2.47.2 (and older) cannot render the in-game Bilibili login page.
Whereas the game comes with the Chromium Embedded Framework (CEF), the Bilibili
SDK does not make use of it. Instead it relies on the Internet Explorer libraries.

Known workaround: Check the "Links" section below.

Note: That project is not directly supported by the patch. Please report issues
and questions to its dedicated page.


**Links / 网页链接**

 * Workaround: https://github.com/QiE2035/gs_bili


#### Controller Configuration

*This section should not be documented in this repository.
If you know of a better public place for documentation, please open an issue
so that this information is available to more people.*

Only follow these instructions if the newest Wine version does not already support your controller.


##### Dualsense

*Source: lahvuun, Issue #216*

1. Open `regedit` in your WINEPREFIX
2. Navigate to `HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\winebus`
3. Create a new DWORD, value `0`, named `Enable SDL`
4. If there is yet no success: check the udev rule section below

Caveats: No force feedback or haptics (vibrations)


##### Other

*Source: Alex72, Issue #228*

General idea: specify the environment variable `SDL_GAMECONTROLLERCONFIG=?????`.

Helpful resources to determine the value (`?????`):

 * For permission-related issues: check the udev rule section below
 * General mapping information: [SDL_GameControllerDB](https://github.com/gabomdq/SDL_GameControllerDB)
 * [SDL2 controller test tool](https://github.com/libsdl-org/SDL/blob/main/test/controllermap.c)
    * Required packages: build tools and SDL2
       * Debian/Ubuntu: `libsdl2-dev`
    * Compile with `gcc -o controllermap controllermap.c $(sdl2-config --libs --cflags)`
    * If compiling fails, either:
       * Install a newer SDL2 library
       * or download an older `controllermap.c` file which matches your installed version
 * [SDL2 Gamepad Mapper](https://gitlab.com/ryochan7/sdl2-gamepad-mapper)
 * [AntiMicroX](https://github.com/AntiMicroX/antimicrox)


##### udev rule configuration

Some specific controllers might lack read permission.

 * If [game-devices-udev](https://gitlab.com/fabiscafe/game-devices-udev) lists your controller, install it.
    * Run `udevadm control --reload-rules` or reboot to apply the changes
 * Arch Wiki instructions for other controllers: [Gamepad](https://wiki.archlinux.org/title/Gamepad)

Maybe helpful: `wine control.exe` shows a simple controller/gamepad testing application.
